feat: introduce dual-generation monorepo architecture #5785

rubencarvalho · 2025-10-06T11:35:45Z

Description

This PR restructures the Spectrum Web Components repository into a dual-generation monorepo to support side-by-side development of 1st-gen and 2nd-gen components. This architectural change is foundational to the project's strategic objectives and enables the team to pursue multiple goals in parallel without disruption.

Key changes:

Moved existing codebase into 1st-gen/ workspace, preserving all existing functionality
Created 2nd-gen/ workspace with initial package structure for @spectrum-web-components/core and @adobe/swc
Established shared Core library (@spectrum-web-components/core) containing abstract, non-rendering base classes that both generations can extend
Updated root configuration for Yarn 4 workspace management, delegating build/test/lint scripts to generation-specific workspaces
Refactored CI/CD (CircleCI and GitHub Actions) to support the new workspace structure
Added comprehensive contributor documentation covering architecture, migration paths, and development workflows

Motivation and context

This change implements the "side-by-side development" strategy outlined in our project objectives, providing two critical advantages:

Isolation: 1st-gen and 2nd-gen workspaces are separated, allowing 2nd-gen to be built iteratively from the ground up without risking breakage to 1st-gen. Disruptive changes (tooling overhauls, Spectrum CSS unification, full-fidelity Spectrum 2 implementation) are confined to 2nd-gen/, while 1st-gen continues operating "as-is".

Colocation: Both generations live in the same repository and share core component logic through abstract base classes in @spectrum-web-components/core. This means:

Non-disruptive improvements (accessibility, bug fixes, features) can be shared immediately across both generations
Customers benefit continuously throughout the transition
Migration from 1st-gen to 2nd-gen will be smoother due to shared API and behavior

This architectural foundation enables the team to work efficiently on multiple strategic objectives in parallel:

Unifying Spectrum CSS & SWC
Building clean tooling and infrastructure
Delivering full-fidelity Spectrum 2
Improving accessibility
Continually enhancing components

See CONTRIBUTOR-DOCS/03_project-planning/01_objectives-and-strategy.md for detailed strategic context.

Related issue(s)

Part of the broader 2nd-gen SWC initiative

fixes [Issue Number]

Screenshots (if appropriate)

Author's checklist

I have read the CONTRIBUTING and PULL_REQUESTS documents.
I have reviewed at the Accessibility Practices for this feature, see: Aria Practices
I have added automated tests to cover my changes.
I have included a well-written changeset if my change needs to be published.
I have included updated documentation if my change required it.

Reviewer's checklist

Includes a Github Issue with appropriate flag or Jira ticket number without a link
Includes thoughtfully written changeset if changes suggested include patch, minor, or major features
Automated tests cover all use cases and follow best practices for writing
Validated on all supported browsers
All VRTs are approved before the author can update Golden Hash

Manual review test cases

All testing and validation happening under SWC-1236.

changeset-bot · 2025-10-06T11:35:50Z

⚠️ No Changeset found

Latest commit: 3ba5e8a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2025-10-06T12:02:16Z

📚 Branch Preview

🔍 Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

Deployed to Azure Blob Storage: pr-5785

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

github-actions · 2025-10-06T12:05:38Z

Tachometer results

Currently, no packages are changed by this PR...

- Add root package.json with workspace delegating scripts - Configure Yarn 4 with monorepo workspaces - Set up lint-staged, commitlint, and patch-package - Update .gitignore for dual-workspace structure - Configure root-level linting and formatting rules

- Create 2nd-gen workspace with separate package.json - Add @spectrum-web-components/core package with shared base classes - Implement 2nd-gen components: asset, alert-banner, divider, progress-circle, status-light, report-abuse-button - Add @adobe/swc aggregator package - Configure Vite-based Storybook for Spectrum 2 - Set up Vitest and Playwright testing infrastructure - Add TypeScript path mappings for cross-generation imports

- Update CircleCI config for 1st-gen and 2nd-gen paths - Modify GitHub workflows for monorepo structure - Update changeset configuration for dual-workspace - Add Cursor rules for contributor documentation

- Add comprehensive contributor documentation - Document 1st-gen vs 2nd-gen split and migration paths - Include component migration step-by-step guides - Add project planning and workstream documentation - Document release processes and testing strategies

…5851) * chore: update and streamline publishing workflow for new monorepo structure Refactors the publishing and release management workflow to support the dual-generation monorepo architecture: - Update Changesets configuration to recognize both 1st-gen and 2nd-gen workspaces, enabling independent versioning strategies - Refactor release scripts to delegate to generation-specific publishing workflows rather than operating on a flat package structure - Update CI/CD publishing jobs to build, test, and publish both generations with appropriate dependency handling for the shared Core library - Preserve existing 1st-gen package publishing behavior to avoid disruption to current consumers This workflow enables continuous delivery of improvements to 1st-gen customers while supporting independent 2nd-gen package releases.

nikkimk

The docs are looking very very nice. Here's what I have for feedback today.

nikkimk · 2025-11-03T19:18:33Z

CONTRIBUTOR-DOCS/01_contributor-guides/01_getting-involved.md

+
+## Developing locally
+
+Read the steps outlined in the [README.md](../README.md) to get your environment set up.


This content moved from root README to Working in the SWC repo

Suggested change

Read the steps outlined in the [README.md](../README.md) to get your environment set up.

Read the steps outlined in [Working in the SWC repo](./03_working-in-the-swc-repo.md) to get your environment set up.

nikkimk · 2025-11-03T19:32:55Z

CONTRIBUTOR-DOCS/01_contributor-guides/03_working-in-the-swc-repo.md

+
+    - The 2nd-gen SWC library (`packages/swc/`).
+
+During this transition, depending on what you're trying to accomplish, you may end up working in `1st-gen`, `2nd-gen`, or both. If you have any questions, [please ask](./01_getting-involved.md#community--support)—we're happy to help.


Should we link to the gen-specific READMEs here?

Suggested change

During this transition, depending on what you're trying to accomplish, you may end up working in `1st-gen`, `2nd-gen`, or both. If you have any questions, [please ask](./01_getting-involved.md#community--support)—we're happy to help.

During this transition, depending on what you're trying to accomplish, you may end up working in `[1st-gen](/1st-gen/README.md)`, `[2nd-gen](/2nd-gen/README.md)`, or both. If you have any questions, [please ask](./01_getting-involved.md#community--support)—we're happy to help.

nikkimk · 2025-11-03T20:15:08Z

CONTRIBUTOR-DOCS/01_contributor-guides/04_making-a-pull-request.md

+- The use of semantic markup.
+- Labeled interactive elements with appropriate accordance's.
+- Accounting for appropriate states, such as focus and keyboard navigation, according to [standards](https://www.w3.org/WAI/perspective-videos/keyboard/).


Suggested change

- The use of semantic markup.

- Labeled interactive elements with appropriate accordance's.

- Accounting for appropriate states, such as focus and keyboard navigation, according to [standards](https://www.w3.org/WAI/perspective-videos/keyboard/).

- The use of semantic markup.

- The appropriate [ARIA roles, properties, and states](https://www.w3.org/WAI/ARIA/apg/example-index/) to indicate affordances that are not already indicated via semantic HTML.

- Applying [descriptive labels](https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/).

- The use of the expected [keyboard navigation](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/).

- Sufficient color contrast as recommended in the [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/).

nikkimk · 2025-11-03T22:13:01Z

CONTRIBUTOR-DOCS/01_contributor-guides/04_making-a-pull-request.md

+- Changeset type should be one of:
+    - `patch` - for bug fixes only
+    - `minor` - for new components or new APIs in an existing component
+    - `major` - for breaking changes to a component or public library API


We have a guide on changesets that should move to Controbutor Docs and be linked from here.

See https://github.com/adobe/spectrum-web-components/blob/main/projects/documentation/content/guides/writing-changesets.md

TarunAdobe · 2025-11-04T06:57:01Z

.github/workflows/lint.yml

                  reporter: github-pr-review
                  filter_mode: diff_context
-                  eslint_flags: '${{ needs.changed_files.outputs.eslint_added_files }} ${{ needs.changed_files.outputs.eslint_modified_files }}'
+                  eslint_flags: '--config .eslintrc.json ${{ needs.changed_files.outputs.eslint_added_files }} ${{ needs.changed_files.outputs.eslint_modified_files }}'


Should we drop the forced --config .eslintrc.json so that ESLint uses per-directory configs and 2nd-gen’s JSON override applies? This would make the lint workflow work exactly how yarn lint works in local envs.

1st-gen/package.json

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

rise-erpelding mentioned this pull request Oct 10, 2025

feat(divider): migrate to second-gen styles and architecture #5798

Merged

27 tasks

caseyisonit added do-not-merge NO MERGE-Y! feature-branch 2nd gen These issues or PRs map to our 2nd generation work to modernizing infrastructure. labels Oct 20, 2025

najikahalsema added do not merge and removed do not merge labels Oct 21, 2025

rubencarvalho changed the title ~~Barebones~~ chore: create second-generation world Oct 22, 2025

rubencarvalho force-pushed the barebones branch from ec211ef to 22de59a Compare November 2, 2025 21:27

rubencarvalho changed the title ~~chore: create second-generation world~~ feat: introduce dual-generation monorepo architecture Nov 2, 2025

rubencarvalho added Status: Ready for review PR ready for review or re-review. High priority PR review PR is a high priority and should be reviewed ASAP labels Nov 2, 2025

rubencarvalho marked this pull request as ready for review November 2, 2025 21:49

rubencarvalho requested a review from a team as a code owner November 2, 2025 21:49

rubencarvalho and others added 6 commits November 3, 2025 15:44

chore: move repository contents under 1st-gen/

b6de7f4

ci: update automation for dual-workspace structure

2eba5be

- Update CircleCI config for 1st-gen and 2nd-gen paths - Modify GitHub workflows for monorepo structure - Update changeset configuration for dual-workspace - Add Cursor rules for contributor documentation

rubencarvalho force-pushed the barebones branch from 3ff495e to fd099fd Compare November 3, 2025 14:45

nikkimk requested changes Nov 3, 2025

View reviewed changes

TarunAdobe reviewed Nov 4, 2025

View reviewed changes

rubencarvalho and others added 2 commits November 4, 2025 17:13

chore: address barebones feedback (#5852)

38a2b8f

chore: adjust linting

a9e20e1

rubencarvalho force-pushed the barebones branch from b117fc5 to a9e20e1 Compare November 4, 2025 16:28

adobe deleted a comment from github-actions bot Nov 4, 2025

github-actions bot reviewed Nov 4, 2025

View reviewed changes

1st-gen/package.json Outdated Show resolved Hide resolved

adobe deleted a comment from github-actions bot Nov 4, 2025

Update 1st-gen/package.json

3ba5e8a

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: introduce dual-generation monorepo architecture #5785

feat: introduce dual-generation monorepo architecture #5785

rubencarvalho commented Oct 6, 2025 •

edited

Loading

Uh oh!

changeset-bot bot commented Oct 6, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Oct 6, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Oct 6, 2025

Uh oh!

nikkimk left a comment

Uh oh!

nikkimk Nov 3, 2025

Uh oh!

nikkimk Nov 3, 2025

Uh oh!

nikkimk Nov 3, 2025

Uh oh!

nikkimk Nov 3, 2025

Uh oh!

TarunAdobe Nov 4, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants


		## Developing locally

		Read the steps outlined in the [README.md](../README.md) to get your environment set up.

	Read the steps outlined in the [README.md](../README.md) to get your environment set up.
	Read the steps outlined in [Working in the SWC repo](./03_working-in-the-swc-repo.md) to get your environment set up.


		- The 2nd-gen SWC library (`packages/swc/`).

		During this transition, depending on what you're trying to accomplish, you may end up working in `1st-gen`, `2nd-gen`, or both. If you have any questions, [please ask](./01_getting-involved.md#community--support)—we're happy to help.

feat: introduce dual-generation monorepo architecture #5785

Are you sure you want to change the base?

feat: introduce dual-generation monorepo architecture #5785

Conversation

rubencarvalho commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Key changes:

Motivation and context

Related issue(s)

Screenshots (if appropriate)

Author's checklist

Reviewer's checklist

Manual review test cases

Uh oh!

changeset-bot bot commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions bot commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Branch Preview

🔍 Visual Regression Test Results

Uh oh!

github-actions bot commented Oct 6, 2025

Tachometer results

Uh oh!

nikkimk left a comment

Choose a reason for hiding this comment

Uh oh!

nikkimk Nov 3, 2025

Choose a reason for hiding this comment

Uh oh!

nikkimk Nov 3, 2025

Choose a reason for hiding this comment

Uh oh!

nikkimk Nov 3, 2025

Choose a reason for hiding this comment

Uh oh!

nikkimk Nov 3, 2025

Choose a reason for hiding this comment

Uh oh!

TarunAdobe Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

rubencarvalho commented Oct 6, 2025 •

edited

Loading

changeset-bot bot commented Oct 6, 2025 •

edited

Loading

github-actions bot commented Oct 6, 2025 •

edited

Loading